[Top] [Prev] [Next] [Bottom] [Contents]

Tutorial 4: Creating and Using an Executable Data Object

This tutorial assumes the following:

If your system is not configured in this way (perhaps for reasons of security), you will be able to follow the tutorial and learn how to make an Executable Data Object, but your final project will not function.

Creating an Executable Data Object

An Executable Data Object is an executable program that can be accessed by the machine that the http server runs on or the machine that the Sapphire/Gateway runs on. The executable object can be a binary executable or an interpreted script (like C shell or Perl). You will create an Executable Data Object that executes the UNIX command man.

1. Open the Object Editor (click the icon or select Tools->Object Editor).
2. Select File->New to create a new object.
3. Select EXEC from the Object Type combo box.
4. Enter man in the Selection text field. Click Ok.
5. Enter man in the Executable Name text field. This is the command that you want the CGI to execute and process.
Now that you have named the object, you need to specify how command line arguments will be sent to the object.
6. You must follow this format when specifying arguments for EXEC Data Objects:
	#name,type,remove_previous#
name: The name of the argument. This will appear in the Object Bind Editor.
type: Can be WRAP or NO_WRAP. WRAP tells the Data Object to wrap the argument value with quotes and NO_WRAP tells it not to wrap the value with quotes.
remove_previous: This is an optional parameter. A value of True means to remove the prefix of this argument if the value returned for the argument is NULL or empty. False means do not remove the prefix.
You want the user to send one command line argument to man. That argument will be named title, and you do not want to wrap quotes around the argument. An argument not wrapped with quotes will be interpreted by the shell before the command is executed. This allows the user to use wild cards for filenames and other shell expansions. It can also open security holes (as we shall see later in this chapter).

7. Enter #title,no_wrap# in the Command-Line text field.
Now that you have specified the input to your Data Object, you need to specify how the output of the object will be displayed. When man is executed at the command line it returns one string that is not formatted into multiple rows and columns. You need to tell Sapphire/Web about this, so that it does not try to parse the output.

The following steps specify that the page will display one column, with column entries delimited by the End Of File character ^D (on most machines). You will specify ^D because this character cannot be in the middle of the output string.

8. Make sure the Delimited toggle button is pressed in.
9. Click the down arrow next to Column Delim and select ^D.
10. Enter output in the Name text field.
11. Click the Add >> button. You have named your output string output.
Your Object Editor should look like Figure 3-17.

12. From the Project Window select File->Save, then select File->Close.

Figure 3-17 The Object Editor

The next binding will define the ManPage Anchor in the index.html document. When this Anchor is clicked, the project CGI will play the manform.html template. There is no dynamic data on this page, so you will use a NULL data object.
13. Click the Object Bind Editor (New Activator) icon.
14. From the Document list select index.html.
15. From the Anchor list select HREF=ManPage. Click Ok.
16. From the Object Type combo box select NULL. Click Ok.
17. At Results<=>Template, select manform.html. Click Ok.
The next binding will define the Submit button in the manform.html document. When this Submit button is clicked your project will take the string entered by the user and pass it (as the argument Title) to the man Executable Data Object. The results of man will be placed into the manres.html template.

18. Click the Object Bind Editor (New Activator) icon.
19. From the Document list select manform.html.
20. From the Forms list select ACTION=FormAction. Click Ok.
21. From the Object Type combo box, select EXEC.
22. From the Executable Objects list, select man. Click Ok.
23. At Arguments<=>Activator, bind the Title form element to the Title Argument.
24. At the Results<=>Template, click the down arrow and select manres.html.
25. Bind the Results site to the Output result. Click Ok.
26. Save and Test the project.

Testing Your Project

After the above steps have been completed, the HTML Browser will appear with index.html. In the following steps you will test your project.

1. Click the Man Page anchor. If you get "error URL not found," your Browser most likely has an older version of index.html in its cache. To correct the problem click the Back button (in your browser) to return to index.html and then click the Reload button to load the latest copy of index.html.
2. Enter ls (or any other UNIX command) and click the Submit button.
Notice the output of the man command now shows up in your browser. If the page does not display a description of your command, skip down to "Troubleshooting."

3. If all is working, use your browser to go Back to the man page form.
4. Enter ls; cat /etc/passwd in the text field and click the Submit button.
Scroll down to the bottom of the page. After the man ls results, you should see the contents of your password file! Your project CGI will accept any UNIX command and pass it along to be executed. This is a considerable security hole. You should now complete tutorial 5 to learn how to fix the project.

If the password file does not appear at the bottom of your page, then your server is probably configured to catch and stop attempts to damage the system via CGIs. You may still wish to complete tutorial 5 so that your server applications will run smoothly on insecure systems.

Troubleshooting

As explained in the introduction to this tutorial, you cannot run this project unless:

If your server cannot Fork and Exec processes from a CGI, you will not be able to run this tutorial project without reconfiguring the server. These sorts of limits may have been put in place to improve system security-ask your sysadmin for specifics.

If the UNIX commands man, ls, and cat are not in the path given to CGI programs by your HTTP server, then they cannot be run by user nobody. This is a common situation. In order for your project to execute these commands, you must enter the full path of the commands when you define your data objects.

For example, to implement the man command:

1. In the Data Object Editor, Open your Data Object man.
2. The Executable Name should be man.
3. From the UNIX command line, enter the command which man. The full path of man will be returned to you. For example, it may be /usr/ucb/man.
4. Enter the full path of man as the Executable Name. Close the Data Object Editor. Save and Test your project.


[Top] [Prev] [Next] [Bottom] [Contents]

info@bluestone.com
Copyright © 1997, Bluestone. All rights reserved.